| backscatterer | backscatterer IPs | x | x | | | [Link](https://www.uceprotect.net/en/index.php) |
| becyber | malicious attacker IPs | x | x | | | [Link](https://github.com/duggytuxy/malicious_ip_addresses) |
| binarydefense | binary defense banlist | x | x | | | [Link](https://iplists.firehol.org/?ipset=bds_atif) |
-| bogon | bogon prefixes | x | x | | | [Link](https://team-cymru.com) |
+| bogon | bogon prefixes | x | x | x | | [Link](https://team-cymru.com) |
| bruteforceblock | bruteforceblocker IPs | x | x | | | [Link](https://danger.rulez.sk/index.php/bruteforceblocker/) |
| country | country blocks | x | x | | | [Link](https://www.ipdeny.com/ipblocks) |
| cinsscore | suspicious attacker IPs | x | x | | | [Link](https://cinsscore.com/#list) |
* Supports concatenation of local MAC addresses with IPv4/IPv6 addresses, e.g. to enforce dhcp assignments
* All local input types support ranges in CIDR notation
* Auto-add the uplink subnet or uplink IP to the local allowlist
-* Prevent common ICMP, UDP and SYN flood attacks and drop spoofed tcp flags & invalid conntrack packets (DDoS attacks) in an additional prerouting chain
+* Prevent common ICMP, UDP and SYN flood attacks and drop spoofed tcp flags & invalid conntrack packets (DoS attacks) in an additional prerouting chain
* Provides a small background log monitor to ban unsuccessful login attempts in real-time (like fail2ban, crowdsec etc.)
* Auto-add unsuccessful LuCI, nginx, Asterisk or ssh login attempts to the local blocklist
-* Auto-add entire subnets to the blocklist Sets based on an additional RDAP request with the monitored suspicious IP
+* Auto-add entire subnets to the blocklist Set based on an additional RDAP request with the monitored suspicious IP
* Fast feed processing as they are handled in parallel as background jobs (on capable multi-core hardware)
* Per feed it can be defined whether the wan-input chain, the wan-forward chain or the lan-forward chain should be blocked (default: all chains)
* Automatic blocklist backup & restore, the backups will be used in case of download errors or during startup
* **[OpenWrt](https://openwrt.org)**, latest stable release or a snapshot with nft/firewall 4 support
* A download utility with SSL support: 'aria2c', 'curl', full 'wget' or 'uclient-fetch' with one of the 'libustream-*' SSL libraries, the latter one doesn't provide support for ETag HTTP header
* A certificate store like 'ca-bundle', as banIP checks the validity of the SSL certificates of all download sites by default
-* For E-Mail notifications you need to install and setup the additional 'msmtp' package
+* For E-Mail notifications you need to install and setup the additional 'msmtp' package
-**Please note:**
-* Devices with less than 256Mb of RAM are **_not_** supported
-* Any previous installation of ancient banIP 0.7.x must be uninstalled, and the /etc/banip folder and the /etc/config/banip configuration file must be deleted (they are recreated when this version is installed)
+Please note: Devices with less than 256Mb of RAM are **_not_** supported
## Installation & Usage
* Update your local opkg repository (_opkg update_)
* Install banIP (_opkg install banip_) - the banIP service is disabled by default
* Install the LuCI companion package 'luci-app-banip' (opkg install luci-app-banip)
* It's strongly recommended to use the LuCI frontend to easily configure all aspects of banIP, the application is located in LuCI under the 'Services' menu
+* To be able to use banIP in a meaningful way, you must activate the service and possibly also activate a few blocklist feeds
* If you're using a complex network setup, e.g. special tunnel interfaces, than untick the 'Auto Detection' option under the 'General Settings' tab and set the required options manually
* Start the service with '/etc/init.d/banip start' and check everything is working by running '/etc/init.d/banip status' and also check the 'Firewall Log' and 'Processing Log' tabs
-* If you're going to configure banIP via CLI, edit the config file '/etc/config/banip' and enable the service (set ban\_enabled to '1'), then add pre-configured feeds via 'ban\_feed' (see the feed list above) and add/change other options to your needs, see the options reference table below
## banIP CLI interface
-* All important banIP functions are accessible via CLI.
+* All important banIP functions are accessible via CLI, too. If you're going to configure banIP via CLI, edit the config file '/etc/config/banip' and enable the service, add pre-configured feeds and add/change other options to your needs, see the options reference table below.
```
~# /etc/init.d/banip
Syntax: /etc/init.d/banip [command]
| ban_loglimit | option | 100 | scan only the last n log entries permanently. A value of '0' disables the monitor |
| ban_logcount | option | 1 | how many times the IP must appear in the log to be considered as suspicious |
| ban_logterm | list | regex | various regex for logfile parsing (default: dropbear, sshd, luci, nginx, asterisk and cgi-remote events) |
-| ban_logreadfile | option | /var/log/messages | alternative location for parsing the log file, e.g. via syslog-ng, to deactivate the standard parsing via logread |
+| ban_logreadfile | option | /var/log/messages | alternative location for parsing a log file via tail, to deactivate the standard parsing via logread |
| ban_autodetect | option | 1 | auto-detect wan interfaces, devices and subnets |
| ban_debug | option | 0 | enable banIP related debug logging |
-| ban_icmplimit | option | 10 | threshold in number of packets to detect icmp DDoS in prerouting chain. A value of '0' disables this safeguard |
-| ban_synlimit | option | 10 | threshold in number of packets to detect syn DDoS in prerouting chain. A value of '0' disables this safeguard |
-| ban_udplimit | option | 100 | threshold in number of packets to detect udp DDoS in prerouting chain. A value of '0' disables this safeguard |
+| ban_icmplimit | option | 10 | threshold in number of packets to detect icmp DoS in prerouting chain. A value of '0' disables this safeguard |
+| ban_synlimit | option | 10 | threshold in number of packets to detect syn DoS in prerouting chain. A value of '0' disables this safeguard |
+| ban_udplimit | option | 100 | threshold in number of packets to detect udp DoS in prerouting chain. A value of '0' disables this safeguard |
| ban_logprerouting | option | 0 | log supsicious packets in the prerouting chain |
| ban_loginput | option | 0 | log supsicious packets in the wan-input chain |
| ban_logforwardwan | option | 0 | log supsicious packets in the wan-forward chain |
| ban_reportdir | option | /tmp/banIP-report | directory where banIP stores the report files |
| ban_backupdir | option | /tmp/banIP-backup | directory where banIP stores the compressed backup files |
| ban_protov4 | option | - / autodetect | enable IPv4 support |
-| ban_protov6 | option | - / autodetect | enable IPv4 support |
+| ban_protov6 | option | - / autodetect | enable IPv6 support |
| ban_ifv4 | list | - / autodetect | logical wan IPv4 interfaces, e.g. 'wan' |
| ban_ifv6 | list | - / autodetect | logical wan IPv6 interfaces, e.g. 'wan6' |
| ban_dev | list | - / autodetect | wan device(s), e.g. 'eth2' |
| ban_trigger | list | - | logical reload trigger interface(s), e.g. 'wan' |
| ban_triggerdelay | option | 20 | trigger timeout during interface reload and boot |
| ban_deduplicate | option | 1 | deduplicate IP addresses across all active Sets |
-| ban_splitsize | option | 0 | split ext. Sets after every n lines/members (saves RAM) |
+| ban_splitsize | option | 0 | split the processing/loading of Sets in chunks of n lines/members (saves RAM) |
| ban_cores | option | - / autodetect | limit the cpu cores used by banIP (saves RAM) |
| ban_nftloglevel | option | warn | nft loglevel, values: emerg, alert, crit, err, warn, notice, info, debug |
| ban_nftpriority | option | -100 | nft priority for the banIP table (the prerouting table is fixed to priority -150) |
| ban_mailprofile | option | ban_notify | mail profile used in 'msmtp' for banIP related notification E-Mails |
| ban_mailnotification | option | 0 | receive E-Mail notifications with every banIP run |
| ban_reportelements | option | 1 | count Set elements in the report, disable this option to speed up the report significantly |
-| ban_resolver | option | - | external resolver used for DNS lookups |
+| ban_resolver | option | - | external resolver used for DNS lookups, by default the local resolver/forwarder will be used |
| ban_remotelog | option | 0 | enable the cgi interface to receive remote logging events |
| ban_remotetoken | option | - | unique token to communicate with the cgi interface |
1.11.114.211
[...]
```
-**default regex for logfile parsing**
+
+## Best practise & tweaks
+**Recommendation for low memory systems**
+nftables supports the atomic loading of firewall rules (incl. elements), which is cool but unfortunately is also very memory intensive. To reduce the memory pressure on low memory systems (i.e. those with 256-512Mb RAM), you should optimize your configuration with the following options:
+
+* point 'ban_basedir', 'ban_reportdir' and 'ban_backupdir' to an external usb drive
+* set 'ban_cores' to '1' (only useful on a multicore system) to force sequential feed processing
+* set 'ban_splitsize' e.g. to '1024' to split the load of an external Set after every 1024 lines/elements
+* set 'ban_reportelements' to '0' to disable the CPU intensive counting of Set elements
+
+**Sensible choice of blocklists**
+The following feeds are just my personal recommendation as an initial setup:
+* cinsscore, debl, turris in WAN-Input and WAN-Forward chain
+* doh in LAN-Forward chain
+
+In total, this feed selection blocks about 20K IP addresses. It may also be useful to include some countries to the country feed in WAN-Input and WAN-Forward chain.
+Please note: don't just blindly activate (too) many feeds at once, sooner or later this will lead to OOM conditions.
+
+**Regular expressions for logfile parsing**
+Like fail2ban, banIP supports logfile scanning and automatic blocking of suspicious attacker IPs. By default the following regex are in place to detect failed login attempts via dropbear, sshd, nginx, asterisk or LuCI.
```
list ban_logterm 'Exit before auth from'
list ban_logterm 'luci: failed login'
list ban_logterm 'SecurityEvent=\"InvalidAccountID\".*RemoteAddress='
list ban_logterm 'received a suspicious remote IP '\''.*'\'''
```
+Just add more log terms to protect additional services, e.g. an openvpn server.
-**allow-/blocklist handling**
-banIP supports local allow and block lists, MAC/IPv4/IPv6 addresses (incl. ranges in CIDR notation) or domain names. These files are located in /etc/banip/banip.allowlist and /etc/banip/banip.blocklist.
+**Allow-/Blocklist handling**
+banIP supports local allow- and block-lists, MAC/IPv4/IPv6 addresses (incl. ranges in CIDR notation) or domain names. These files are located in /etc/banip/banip.allowlist and /etc/banip/banip.blocklist.
Unsuccessful login attempts or suspicious requests will be tracked and added to the local blocklist (see the 'ban_autoblocklist' option). The blocklist behaviour can be further tweaked with the 'ban_nftexpiry' option.
Depending on the options 'ban_autoallowlist' and 'ban_autoallowuplink' the uplink subnet or the uplink IP will be added automatically to local allowlist.
Furthermore, you can reference external Allowlist URLs with additional IPv4 and IPv6 feeds (see 'ban_allowurl').
Both local lists also accept domain names as input to allow IP filtering based on these names. The corresponding IPs (IPv4 & IPv6) will be extracted and added to the Sets. You can also start the domain lookup separately via /etc/init.d/banip lookup at any time.
-**allowlist-only mode**
-banIP supports an "allowlist only" mode. This option skips all blocklists and restricts the internet access only to specific, explicitly allowed IP segments - and block access to the rest of the internet. All IPs which are _not_ listed in the allowlist (plus the external Allowlist URLs) are blocked.
+**Allowlist-only mode**
+banIP supports an "allowlist only" mode. This option skips all blocklists and restricts Internet access only to certain, explicitly permitted IP segments - and blocks access to the rest of the Internet. All IPs that are _not_ listed in the allowlist or in the external allowlist URLs are blocked. In this mode it might be useful to limit the allowlist feed to the wan-input / wan-forward chain, to still allow lan-forward communication to the rest of the world.
**MAC/IP-binding**
-banIP supports concatenation of local MAC addresses/ranges with IPv4/IPv6 addresses, e.g. to enforce dhcp assignments. Following notations in the local allow and block lists are allowed:
+banIP supports concatenation of local MAC addresses/ranges with IPv4/IPv6 addresses, e.g. to enforce dhcp assignments.
+The following notations in the local allow- and block-list are supported:
```
MAC-address only:
C8:C2:9B:F7:80:12 => this will be populated to the v4MAC- and v6MAC-Sets with the IP-wildcards 0.0.0.0/0 and ::/0
C8:C2:9B:F7:80:12 => this will be populated to v6MAC-Set with the IP-wildcard ::/0
```
-**enable the cgi interface to receive remote logging events**
+**CGI interface to receive remote logging events**
banIP ships a basic cgi interface in '/www/cgi-bin/banip' to receive remote logging events (disabled by default). The cgi interface evaluates logging events via GET or POST request (see examples below). To enable the cgi interface set the following options:
* set 'ban_remotelog' to '1' to enbale the cgi interface
Please note: for security reasons use this cgi interface only internally and only encrypted via https transfer protocol.
-**redirect Asterisk security logs to lodg/logread**
-banIP only supports logfile scanning via logread, so to monitor attacks on Asterisk, its security log must be available via logread. To do this, edit '/etc/asterisk/logger.conf' and add the line 'syslog.local0 = security', then run 'asterisk -rx reload logger' to update the running Asterisk configuration.
-
-**send status E-Mails and update the banIP lists via cron job**
-For a regular, automatic status mailing and update of the used lists on a daily basis set up a cron job, e.g.
-```
-55 03 * * * /etc/init.d/banip report mail
-00 04 * * * /etc/init.d/banip reload
-```
-
-**tweaks for low memory systems**
-nftables supports the atomic loading of firewall rules (incl. elements), which is cool but unfortunately is also very memory intensive. To reduce the memory pressure on low memory systems (i.e. those with 256-512Mb RAM), you should optimize your configuration with the following options:
-
- * point 'ban_basedir', 'ban_reportdir' and 'ban_backupdir' to an external usb drive
- * set 'ban_cores' to '1' (only useful on a multicore system) to force sequential feed processing
- * set 'ban_splitsize' e.g. to '1000' to split the load of an external Set after every 1000 lines/members
- * set 'ban_reportelements' to '0' to disable the CPU intensive counting of Set elements
-
-**tweak the download options**
+**Download options**
By default banIP uses the following pre-configured download options:
```
* aria2c: --timeout=20 --retry-wait=10 --max-tries=5 --max-file-not-found=5 --allow-overwrite=true --auto-file-renaming=false --log-level=warn --dir=/ -o
```
To override the default set 'ban_fetchretry', 'ban_fetchinsecure' or globally 'ban_fetchparm' to your needs.
-**send E-Mail notifications via 'msmtp'**
-To use the email notification you must install & configure the package 'msmtp'.
+**Configure E-Mail notifications via 'msmtp'**
+To use the email notification you must install and configure the package 'msmtp'.
Modify the file '/etc/msmtprc', e.g.:
```
[...]
user <gmail-user>
password <password>
```
-Finally add a valid E-Mail receiver address.
+Finally add a valid E-Mail receiver address in banIP.
-**change existing banIP feeds or add port limitations**
+**Send status E-Mails and update the banIP lists via cron job**
+For a regular, automatic status mailing and update of the used lists on a daily basis set up a cron job, e.g.
+```
+55 03 * * * /etc/init.d/banip report mail
+00 04 * * * /etc/init.d/banip reload
+```
+**Redirect asterisk security logs to lodg/logread**
+By default banIP scans the logfile via logread, so to monitor attacks on asterisk, its security log must be available via logread. To do this, edit '/etc/asterisk/logger.conf' and add the line 'syslog.local0 = security', then run 'asterisk -rx reload logger' to update the running asterisk configuration.
+
+**Change/add banIP feeds and port limitations**
The banIP default blocklist feeds are stored in an external JSON file '/etc/banip/banip.feeds'. All custom changes should be stored in an external JSON file '/etc/banip/banip.custom.feeds' (empty by default). It's recommended to use the LuCI based Custom Feed Editor to make changes to this file.
A valid JSON source object contains the following information, e.g.:
```
Add an unique feed name (no spaces, no special chars) and make the required changes: adapt at least the URL, the regex and the description for a new feed.
Please note: the flag field is optional, it's a space separated list of options: supported are 'gz' as an archive format, protocols 'tcp' or 'udp' with port numbers/port ranges for destination port limitations - multiple definitions are possible.
-## FAQ
-TODO!
+**Debug options**
+Whenever you encounter banIP related processing problems, please check the "Processing Log" tab.
+Typical symptoms:
+* The nftables initialization failed: untick the 'Auto Detection' option in the 'General Settings' config section and set the required options manually
+* A blocklist feed does not work: maybe a temporary server problem or the download URL has been changed. In the latter case, just use the Custom Feed Editor to point this feed to a new URL
+To get much more processing information, please enable "Verbose Debug Logging" and restart banIP.
+
+Whenever you encounter firewall problems, enable the logging of certain chains in the "Log Settings" config section, restart banIP and check the "Firewall Log" tab.
+Typical symptoms:
+* A feed blocks a legit IP: disable the entire feed or add this IP to your local allowlist and reload banIP
+* A feed (e.g. doh) interrupts almost all client connections: check the feed table above for reference and limit the feed to a certain chain in the "Feed/Set Settings" config section
+* The allowlist doesn't free a certain IP/MAC address: check the current content of the allowlist with the "Set Survey" under the "Set Reporting" tab to make sure that the desired IP/MAC is listed - if not, reload banIP
## Support
-Please join the banIP discussion in this [forum thread](https://forum.openwrt.org/t/banip-support-thread/16985) or contact me by mail <dev@brenken.org>
+Please join the banIP discussion in this [forum thread](https://forum.openwrt.org/t/banip-support-thread/16985) or contact me by mail <dev@brenken.org>
+If you want to report an error, please describe it in as much detail as possible - with (debug) logs, the current banIP status, your banIP configuration, etc.
## Removal
-* stop all banIP related services with _/etc/init.d/banip stop_
-* remove the banip package (_opkg remove banip_)
+Stop all banIP related services with _/etc/init.d/banip stop_ and remove the banip package if necessary.
+
+## Donations
+You like this project - is there a way to donate? Generally speaking "No" - I have a well-paying full-time job and my OpenWrt projects are just a hobby of mine in my spare time.
+
+If you still insist to donate some bucks ...
+* I would be happy if you put your money in kind into other, social projects in your area, e.g. a children's hospice
+* Let's meet and invite me for a coffee if you are in my area, the “Markgräfler Land” in southern Germany or in Switzerland (Basel)
+* Send your money to my [PayPal account](https://www.paypal.me/DirkBrenken) and I will collect your donations over the year to support various social projects in my area
+
+No matter what you decide - thank you very much for your support!
Have fun!
Dirk
projects / feed / packages.git / commitdiff